/*
* @(#) NotationHelper.java 1.0 13/01/2010
* Package: com.toc.dton
*
* Copyright 2009 TOC, Studio. All rights reserved.
*/
package com.toc.dton;
import com.toc.dton.notation.xml.XMLNotation;
/**
* <p><b>About DTON (Data Transfer Object Notation)</b>
* <p>DTON helper you to transform the Java Data Transfer Object to a character format notation or reverse it.
* <p>Simply put, Java Data Transfer Object is a plain java object which used to store the useful data and the data need to be transfered.
* <ul><b>We define 5 types Data Transfer Object:</b>
* <li>Value - Value is the object to store a single value, for example, {@code String}, {@code Date}, {@code int} etc.
* <li>Bean - Bean is the object to store variable type of Data Transfer Object, it is a plain java object contain the fields to store the data.
* <li>List - List is a group of Data Transfer Object, we consider the type is a List if it implements the interface {@code java.util.Collection}, such as {@code java.util.ArrayList}.
* <li>Map - Map can maps key to Data Transfer Object, means it can contain several set of key-DTO, we consider the type is a Map if it implements the interface {@code java.util.Map}, such as {@code java.util.HashMap}.
* <li>Array - Array map to Java Array (like int[]), if call the method of {@code isArray()} of the class returns true, we considerate it is a Array object.
* </ul>
* <ul><b>Currently we support to transform DTO to below style notation:</b>
* <li>XML - The specification of the XML Notation you can refers to {@link com.toc.dton.notation.xml.XMLNotationDefinition XMLNotationDefinition}.
* </ul>
*
* <p><b>Special instruct of Transform the Bean Type DTO in TOC DTON:</b>
* Different from other DTO Types, although DTO Bean is a plain java object, but cannot use plain java object directly as a Bean object in TOC DTON.
* The DTO Bean should following the specification as below:
* <ul>
* <li>Must add DTON Annotation ({@link com.toc.dton.Property Property}) before the field which need to be transformed.
* <li>Once the field be remark with DTON Annotation, must add two method to get and set the field.
* <li>The 'get' method must with no parameter, and return a field type value, usually return the field directly.
* <li>The 'set' method must with no return value and accept one field type parameter, usually put the parameter to field.
* <li>The 'get' and 'set' method need follow the naming rule as below, it similar with java name convention.
* <ul type=circle><li>The 'get' method start with 'get' and follow the field name with first character upper case. For example, String field name is {@code billAddress}, the 'get' method will be {@code String getBillAddress()}.
* <li>The 'set' method start with 'set' and follow the field name with first character upper case. For example, String field name is {@code billAddress}, the 'set' method will be {@code void getBillAddress(String address)}.
* <li><b>Note:</b> Different from java name convention, for boolean/Boolean type field please still use 'get' as the prefix of the 'get' method instead of 'is' in java naming convention.
* </ul>
* </ul>
* <p>Below is an example of DTON Bean:
* <pre>
* import com.toc.dton.Property;
* public class BeanSample {
* @Property
* private int testInt;
* @Property
* private BeanSample beanSample;
* public int getTestInt() {
* return testInt;
* }
* public void setTestInt(int testInt) {
* this.testInt = testInt;
* }
* public TestBean getTestBean() {
* return testBean;
* }
* public void setTestBean(TestBean testBean) {
* this.testBean = testBean;
* }
* }
* </pre>
* <ol><b>2 Step to use DTON Object:</b>
* <li>First use {@link NotationHelper} to create a {@link Notation} Object.
* <li>Use {@link Notation#decode(Object) decode} or {@link Notation#encode(Object, java.io.OutputStream) encode} to transfer between DTO Object and DTON Notation.
* </ol>
* <p>Title: Notation Helper(Factory)
* <p>Description:
* <p>This class is to help user create a Notation Object, considerate we may extends the DTON to support various notation type such as XML, JSON, Properity etc.
* <p><b>Note:</b> Currently, DTON only support XML Notation.
* <p>Copyright: Copyright (c) 2010 Thousand Origami Cranes Corp.
* <p>Create Time: 13 Jan 2010 14:34:21
* @author Kevin.Zhou
* @version 1.0
* @see com.toc.dton.Notation
* @see com.toc.dton.notation.xml.XMLNotation
*/
public class NotationHelper {
/**
* Create a new XML Notation Processor
* <p>Create Time: 13 Jan 2010 14:45:01
* <br>Author: Kevin.Zhou
* @return {@link Notation}
*/
public static Notation createXMLNotation() {
return new XMLNotation();
}
}